---
title: Astro 설치
sidebar:
  label: 설치
description: 'Astro를 설치하고 새 프로젝트를 시작하는 방법'
i18nReady: true
---
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

[`create astro` CLI 명령](#cli-마법사로-설치)은 처음부터 새로운 Astro 프로젝트를 시작하는 가장 빠른 방법입니다. 새로운 Astro 프로젝트 설정의 모든 단계를 안내하며 몇 가지 공식 스타터 템플릿 중에서 선택할 수 있도록 합니다.

`template` 플래그와 함께 CLI 명령을 실행하여 기존 테마 또는 스타터 템플릿을 사용하여 프로젝트를 시작할 수도 있습니다. 블로그, 포트폴리오, 문서 사이트, 랜딩 페이지 등을 위한 테마를 찾아볼 수 있는 [테마 및 스타터 쇼케이스](https://astro.build/themes/)를 살펴보세요!

Astro를 수동으로 설치하려면 [단계별 수동 설치 가이드](#수동-설정)를 참조하세요.

:::tip[온라인 미리보기]
브라우저에서 Astro를 사용해 보시겠습니까? [astro.new](https://astro.new/)를 방문하여 스타터 템플릿을 찾아보고 브라우저를 떠나지 않고도 새로운 Astro 프로젝트를 시작하세요.
:::

## 사전 준비 사항

- **Node.js** - `v18.20.8` 또는 `v20.3.0`, `v22.0.0` 이상 (`v19` 및 `v21`은 지원되지 않습니다.)
- **텍스트 편집기** - [공식 Astro 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)이 포함된 [VS Code](https://code.visualstudio.com/)를 권장합니다.
- **터미널** - Astro는 CLI (명령줄 인터페이스)를 통해 액세스됩니다.

## 브라우저 호환성

Astro는 기본적으로 최신 JavaScript를 지원하는 브라우저를 대상으로 하는 Vite로 빌드되었습니다. 전체 참조는 [Vite에서 현재 지원되는 브라우저 버전 목록](https://ko.vite.dev/guide/build.html#browser-compatibility)을 확인하세요.

## CLI 마법사로 설치

`create astro`는 컴퓨터 어디에서든 실행할 수 있으므로 시작하기 전에 프로젝트를 위한 새 빈 디렉터리를 만들 필요가 없습니다. 새 프로젝트를 위한 빈 디렉터리가 아직 없는 경우 마법사가 자동으로 디렉터리를 만드는 데 도움을 줍니다.

<Steps>
1. 터미널에서 다음 명령을 실행하여 설치 마법사를 시작합니다.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # npm으로 새 프로젝트 시작
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # pnpm으로 새 프로젝트 시작
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # yarn으로 새 프로젝트 시작
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>
    
    모든 것이 잘 진행되면 성공 메시지와 함께 몇 가지 권장되는 다음 단계가 표시됩니다.
    
2. 이제 프로젝트가 생성되었으므로 새 프로젝트 디렉터리로 `cd`하여 Astro를 시작할 수 있습니다.

3. CLI 마법사에서 "Install dependencies?" 단계를 건너뛴 경우 계속하기 전에 의존성을 설치해야 합니다.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm install
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn install
      ```
      </Fragment>
    </PackageManagerTabs>

4. 이제 [Astro 개발 서버를 시작](/ko/develop-and-build/#astro-개발-서버-시작)하고 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!
</Steps>

## CLI 설치 플래그

`create astro` 명령을 추가 플래그와 함께 실행하여 설정 프로세스 (예: 모든 질문에 "yes"로 응답, Houston 애니메이션 건너뛰기) 또는 새 프로젝트 (예: git 설치 여부, 통합 추가)를 사용자 정의할 수 있습니다.

<ReadMore>[사용 가능한 모든 `create astro` 명령 플래그](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md)를 확인하세요.</ReadMore>

### 통합 추가

`create astro` 명령에 `--add` 인수를 전달하여 `astro add` 명령을 지원하는 [공식 통합](/ko/guides/integrations-guide/) 또는 커뮤니티 통합을 설치하면서 새 Astro 프로젝트를 시작할 수 있습니다.

터미널에서 `astro add` 명령을 지원하는 다른 통합으로 대체하여, 다음 명령을 실행합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
  npm create astro@latest -- --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
  pnpm create astro@latest --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
  yarn create astro --add react --add partytown
  ```
  </Fragment>
</PackageManagerTabs>

### 테마 또는 스타터 템플릿 사용

`create astro` 명령에 `--template` 인수를 전달하여 [공식 예제](https://github.com/withastro/astro/tree/main/examples) 또는 GitHub 리포지토리의 `main` 브랜치를 기반으로 새 Astro 프로젝트를 시작할 수 있습니다.

터미널에서 사용하려는 테마의 공식 Astro 스타터 템플릿 이름 또는 GitHub 사용자 이름과 리포지토리로 대체하여 다음 명령을 실행합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 공식 예제로 새 프로젝트를 만듭니다.
  npm create astro@latest -- --template <example-name>

  # GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
  npm create astro@latest -- --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 공식 예제로 새 프로젝트를 만듭니다.
  pnpm create astro@latest --template <example-name>
  
  # GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
  pnpm create astro@latest --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 공식 예제로 새 프로젝트를 만듭니다.
  yarn create astro --template <example-name>
  
  # GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
  yarn create astro --template <github-username>/<github-repo>
  ```
  </Fragment>
</PackageManagerTabs>

기본적으로 이 명령은 템플릿 리포지토리의 `main` 브랜치를 사용합니다. 다른 브랜치 이름을 사용하려면 `--template` 인수의 일부로 전달하세요. `<github-username>/<github-repo>#<branch>`

## 수동 설정

이 가이드에서는 새 Astro 프로젝트를 수동으로 설치하고 구성하는 단계를 안내합니다.

자동 `create astro` CLI 도구를 사용하지 않으려면 아래 가이드에 따라 직접 프로젝트를 설정할 수 있습니다.

<Steps>
1. 디렉터리를 만듭니다.
    
    프로젝트 이름으로 빈 디렉터리를 만들고 해당 디렉터리로 이동합니다.

    ```bash
    mkdir my-astro-project
    cd my-astro-project
    ```
    
    새 디렉터리에 프로젝트의 `package.json` 파일을 만듭니다. 이 파일은 Astro를 포함하여 프로젝트 의존성을 관리하는 데 사용됩니다. 이 파일 형식에 익숙하지 않은 경우 다음 명령을 실행하여 파일을 만듭니다.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm init --yes
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm init 
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn init --yes
      ```
      </Fragment>
    </PackageManagerTabs>

2. Astro를 설치합니다.
    
    먼저, 프로젝트에 Astro 프로젝트 의존성을 설치합니다.

    :::note[중요]    
    Astro는 전역이 아닌 로컬에 설치해야 합니다. `npm install -g astro`, `pnpm add -g astro` 또는 `yarn add global astro`를 실행하고 있지 *않은지* 확인하세요.
    :::

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install astro
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add astro
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add astro
      ```
      </Fragment>
    </PackageManagerTabs>
    
    그런 다음 `package.json`의 자리 표시자 "scripts" 섹션을 다음으로 바꿉니다.

    ```json title="package.json" del={3} ins={4-6}
    {
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },
    }
    ```
    
    이러한 스크립트는 이 가이드의 뒷부분에서 Astro를 시작하고 다양한 명령을 실행하는 데 사용됩니다.

3. 첫 페이지를 만듭니다.
    
    텍스트 편집기에서 `src/pages/index.astro`에 새 파일을 만듭니다. 이것은 프로젝트의 첫 번째 Astro 페이지가 됩니다.
    
    이 가이드에서는 다음 코드 스니펫 (`---` 대시 포함)을 새 파일에 복사하여 붙여넣습니다.

    ```astro title="src/pages/index.astro"
    ---
    // Astro에 오신 것을 환영합니다!
    // 이 삼중 대시 코드 펜스 사이의 모든 것은 "컴포넌트 프런트매터"입니다.
    // 브라우저에서 절대 실행되지 않습니다.
    console.log('이것은 브라우저가 아닌 터미널에서 실행됩니다!');
    ---
    <!-- 아래는 "컴포넌트 템플릿"입니다.
        HTML일 뿐이지만, 훌륭한 템플릿을 만드는 데 도움이 되는 몇 가지 마법이 뿌려져 있습니다. -->
    <html>
      <body>
        <h1>Hello, World!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>
    ```

4. 첫 번째 정적 자산을 만듭니다.
        
    정적 자산을 저장할 `public/` 디렉터리를 만들어야 합니다. Astro는 이러한 자산을 최종 빌드에 항상 포함하므로 컴포넌트 템플릿에서 안전하게 참조할 수 있습니다.
    
    텍스트 편집기에서 `public/robots.txt`에 새 파일을 만듭니다. `robots.txt`는 Google과 같은 검색 봇에게 사이트 처리 방법을 알리기 위해 대부분의 사이트에서 포함하는 간단한 파일입니다.
    
    이 가이드에서는 다음 코드 스니펫을 새 파일에 복사하여 붙여넣습니다.

    ```diff title="public/robots.txt"
    # 예시: 모든 봇이 사이트를 스캔하고 색인하도록 허용합니다.
    # 전체 구문: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
    ```

5. `astro.config.mjs`를 만듭니다.
    
    Astro는 `astro.config.mjs`를 사용하여 구성됩니다. 이 파일은 Astro를 구성할 필요가 없는 경우 선택 사항이지만 지금 만드는 것이 좋습니다.
    
    프로젝트 루트에 `astro.config.mjs`를 만들고 아래 코드를 복사하여 붙여넣습니다.

    ```js title="astro.config.mjs"
    import { defineConfig } from "astro/config";

    // https://astro.build/config
    export default defineConfig({});
    ```
    
    React, Svelte 등과 같은 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/)를 포함하거나 프로젝트에서 MDX 또는 Partytown과 같은 다른 도구를 사용하려면 여기에서 [통합을 수동으로 가져오고 구성](/ko/guides/integrations-guide/)합니다.
    
    <ReadMore>자세한 내용은 Astro의 [API 구성 참조](/ko/reference/configuration-reference/)를 확인하세요.</ReadMore>

6. TypeScript 지원을 추가합니다.
    
    TypeScript는 `tsconfig.json`을 사용하여 구성됩니다. TypeScript 코드를 작성하지 않더라도 이 파일은 Astro 및 VS Code와 같은 도구가 프로젝트를 이해하는 방법을 알 수 있도록 하는 데 중요합니다. 일부 기능 (예: npm 패키지 가져오기)은 `tsconfig.json` 파일 없이는 편집기에서 완전히 지원되지 않습니다.
    
    TypeScript 코드를 작성하려는 경우 Astro의 `strict` 또는 `strictest` 템플릿을 사용하는 것이 좋습니다.  [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/)에서 세 가지 템플릿 구성을 확인하고 비교할 수 있습니다.
    
    프로젝트 루트에 `tsconfig.json`을 만들고 아래 코드를 복사하여 붙여넣습니다. (TypeScript 템플릿으로 `base`, `strict` 또는 `strictest`를 사용할 수 있습니다.)

    ```json title="tsconfig.json" "base"
    {
      "extends": "astro/tsconfigs/base"
    }
    ```
    
    <ReadMore>자세한 내용은 Astro의 [TypeScript 설정 가이드](/ko/guides/typescript/#설정)를 참조하세요.</ReadMore>

7. 다음 단계
    
    위의 단계를 따랐으면 프로젝트 디렉터리가 다음과 같이 표시됩니다.

    <FileTree>
    - node_modules/
    - public/
      - robots.txt
    - src/
      - pages/
        - index.astro
    - astro.config.mjs
    - package-lock.json 또는 `yarn.lock`, `pnpm-lock.yaml` 등
    - package.json
    - tsconfig.json
    </FileTree>

8. 이제 [Astro 개발 서버를 시작](/ko/develop-and-build/#astro-개발-서버-시작)하고 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!

</Steps>
